github.com/hyperion-hyn/go-ethereum@v2.4.0+incompatible/docs/Privacy/Tessera/Tessera Services/Keys/Keys.md (about)

     1  ## Generating keys
     2   
     3  Key generation can be used in multiple ways:
     4  
     5  1. Generate a key pair and save in new files `.pub` and `.key`:  
     6      ```
     7      tessera -keygen
     8      ```
     9      This command will require interactive input for passwords. 
    10  If you wish to generate an unlocked key, `/dev/null` can be used for stdin to tell the application not to expect any input (version 0.8 only):
    11      ```
    12      # Version 0.8+
    13      tessera -keygen < /dev/null
    14  
    15      # Version 0.7.x or before
    16      printf "\n\n" | tessera -keygen
    17      ```
    18  
    19      The `-filename` option can be used to specify alternate filepaths.  Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
    20      ```
    21      tessera -keygen -filename /path/to/key1,/path/to/key2
    22      ```
    23  
    24  1. Generate a key pair and save to an Azure Key Vault, with DNS name `<url>`, as secrets with IDs `Pub` and `Key`:
    25      ```
    26      tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url>
    27      ```
    28      
    29      The `-filename` option can be used to specify alternate IDs.  Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
    30      ```
    31      tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url> -filename id1,id2
    32      ```
    33      
    34      **Note: If saving new keys with the same ID as keys that already exist in the vault, the existing keys will be replaced by the newer version.**
    35      
    36      > Environment variables must be set if using an Azure Key Vault, for more information see [Setting up an Azure key vault](../Setting%20up%20an%20Azure%20Key%20Vault)
    37      
    38  1. Generate a key pair and save to a Hashicorp Vault at the secret path `secretEngine/secretName` with IDs `publicKey` and `privateKey`:
    39      ```bash
    40      tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
    41         -keygenvaultsecretengine secretEngine -filename secretName 
    42      ```
    43      Options exist for configuring TLS and AppRole authentication (by default the AppRole path is set to `approle`):
    44      ```bash
    45      tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
    46         -keygenvaultsecretengine <secretEngineName> -filename <secretName> \
    47         -keygenvaultkeystore <JKS file> -keygenvaulttruststore <JKS file> \
    48         -keygenvaultapprole <authpath>
    49      ```
    50      The `-filename` option can be used to generate and store multiple key pairs at the same time:
    51      ```bash
    52      tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
    53         -keygenvaultsecretengine secretEngine -filename myNode/keypairA,myNode/keypairB 
    54      ```
    55      **Saving a new key pair to an existing secret will overwrite the values stored at that secret.  Previous versions of secrets may be retained and be retrievable by Tessera depending on how the K/V secrets engine is configured.  See [Keys](../../../Configuration/Keys) for more information on configuring Tessera for use with Vault.**
    56      
    57      > Environment variables must be set if using a Hashicorp Vault, and a version 2 K/V secret engine must be enabled.  For more information see [Setting up a Hashicorp Vault](../Setting%20up%20a%20Hashicorp%20Vault).
    58  
    59  1. Generate a key pair, save to files and then start Tessera using a provided config
    60      ```
    61      tessera -keygen -configfile /path/to/config.json
    62      ```
    63      ```
    64      tessera -keygen -filename key1 -configfile /path/to/config.json 
    65      ```
    66      Tessera loads `config.json` as usual and includes the newly generated key data before starting.  
    67      
    68      An updated `.json` configfile is printed to the terminal (or to a file if using the `-output` CLI option).  No changes are made to the `config.json` file itself.
    69  
    70  ## Securing private keys
    71  Generated private keys can be encrypted with a password.  This is prompted for on the console during key generation.  After generating password-protected keys, the password must be added to your configuration to ensure Tessera can read the keys.  The password is not saved anywhere but must be added to the configuration else the key will not be able to be decrypted.  
    72  
    73  Passwords can be added to the json config either inline using `"passwords":[]`, or stored in an external file that is referenced by `"passwordFile": "Path"`.  Note that the number of arguments/file-lines provided must equal the total number of private keys.  For example, if there are 3 total keys and the second is not password secured, the 2nd argument/line must be blank or contain dummy data.
    74  
    75  Tessera uses Argon2 in the process of encrypting private keys.  By default, Argon2 is configured as follows:
    76  ```
    77  {
    78      "variant": "id",
    79      "memory": 1048576,
    80      "iterations": 10,
    81      "parallelism": 4
    82  }
    83  ```
    84  The Argon2 configuration can be altered by using the `-keygenconfig` option.  Any override file must have the same format as the default configuration above and all options must be provided.
    85  ```
    86  tessera -keygen -filename /path/to/key1 -keygenconfig /path/to/argonoptions.json
    87  ```
    88  
    89  For more information on Argon2 see the [Argon2 Github page](https://github.com/P-H-C/phc-winner-argon2).
    90  
    91  ### Updating password protected private keys
    92  The password of a private key stored in a file can be updated.  Password update uses the `--keys.keyData.privateKeyPath` CLI option to get the path to the file. 
    93  
    94  Password update can be used in multiple ways.  Running any of these commands will start a CLI prompt to allow you to set a new password.
    95  
    96  1. Add a password to an unlocked key
    97      ```
    98      tessera -updatepassword --keys.keyData.privateKeyPath /path/to/.key
    99      ```
   100      
   101  1. Change the password of a locked key.  This requires providing the current password for the key (either inline or as a file)
   102      ```
   103      tessera -updatepassword --keys.keyData.privateKeyPath /path/to/.key --keys.passwords <password>
   104      ```
   105      or
   106      ```
   107      tessera -updatepassword --keys.keyData.privateKeyPath /path/to/.key --keys.passwordFile /path/to/pwds
   108      ```
   109  
   110  1. Use different Argon2 options from the defaults when updating the password
   111      ```
   112      tessera --keys.keyData.privateKeyPath <path to keyfile> --keys.keyData.config.data.aopts.algorithm <algorithm> --keys.keyData.config.data.aopts.iterations <iterations> --keys.keyData.config.data.aopts.memory <memory> --keys.keyData.config.data.aopts.parallelism <parallelism>
   113      ```
   114      All options have been overriden here but only the options you wish to alter from their defaults need to be provided.